home *** CD-ROM | disk | FTP | other *** search
/ Meeting Pearls 2 / Meeting Pearls Vol. II (1995)(GTI - Schatztruhe)[!].iso / html / ums.doc < prev   
Text File  |  1995-01-22  |  67KB  |  1,811 lines
  1. TABLE OF CONTENTS
  2.  
  3. ums.library/--background--
  4. ums.library/--loginguide--
  5. ums.library/--msg-format--
  6. ums.library/--attributes--
  7. ums.library/UMSCannotExport
  8. ums.library/UMSDeleteMsg
  9. ums.library/UMSDupAccount
  10. ums.library/UMSErrNum
  11. ums.library/UMSErrTxt
  12. ums.library/UMSErrTxtFromNum
  13. ums.library/UMSExportedMsg
  14. ums.library/UMSFreeConfig
  15. ums.library/UMSFreeMsg
  16. ums.library/UMSLog
  17. ums.library/UMSLogin
  18. ums.library/UMSLogout
  19. ums.library/UMSMatchConfig
  20. ums.library/UMSReadConfig
  21. ums.library/UMSReadMsg
  22. ums.library/UMSRLogin
  23. ums.library/UMSSearch
  24. ums.library/UMSSelect
  25. ums.library/UMSServerControl
  26. ums.library/UMSWriteConfig
  27. ums.library/UMSWriteMsg
  28.  
  29. ums.library/--background--                         ums.library/--background--
  30.  
  31.        $VER: 10.21 (28-Aug-93)
  32.  
  33.        COPYRIGHT
  34.  
  35.          This document is (C) 1992 by Martin Horneffer.
  36.  
  37.          It may freely be copied and distributed, as long as the text is
  38.        unchanged and this copyright notice is left intact.
  39.  
  40.        GENERAL
  41.  
  42.          UMS stands for "Universal Message System".
  43.  
  44.          This  means  that  UMS  allows  to  treat  and read all kinds of
  45.        messages  ('e-mail'  and 'news') as universally and efficiently as
  46.        possible.
  47.  
  48.          The  user  should  not need to care about what network a message
  49.        comes  from  or goes to/through and what format is used, he or she
  50.        should be able to concentrate totally on the messages' contents.
  51.  
  52.          In order to achieve this goal, UMS does two things:
  53.  
  54.          1) define an universal format for messages where messages in all
  55.        formats  and  from  all  networks can be stored in without loss of
  56.        information and nevertheless being randomly interchangeable.
  57.  
  58.          2) implement  a central, network-independent database-mamagement
  59.        that  allows to store and read/retrieve messages in the UMS format
  60.        as efficiently as possible.
  61.  
  62.          For  the message format, please read the separate documentation.
  63.  
  64.          The  implementation  of  the  Message  Base Processor ('MBP') is
  65.        based  on  the server/client- concept.  Clients address the server
  66.        to  get  or  put  messages.   The  server  manages the storage and
  67.        retrieval   of   messages  and  controls  the  different  client's
  68.        access-rights  to the system.  The common interface between client
  69.        and server is a set of functions described in this document.
  70.  
  71.          Clients are
  72.          -  simple  USERS  that  read  and write messages (using programs
  73.        called 'newsreaders'),
  74.          -  a  special  kind  of  user, the 'SYSOP', which has additional
  75.        rights and tools to administer the system,
  76.          -  IMPORTERS,  that get messages form other systems and put them
  77.        into the local system after converting them to the UMS format, and
  78.          -  EXPORTERS,  that  look for all NEW messages in the system and
  79.        send them to other systems after converting them into the specific
  80.        format.
  81.  
  82.          The  MBP  controls  which user may read what message and, in the
  83.        same  way, which exporter needs to export or forward what message.
  84.        It  cares  about whether a message can or cannot be correctly sent
  85.        to its destination.
  86.          The  MBP  also  performs  dupe-checking  and  reply-chaining  on
  87.        Message-IDs.
  88.  
  89.  
  90.        TAGS
  91.  
  92.          UMS uses some bit-masking in tag values to indicate some special
  93.        types of tag data:
  94.  
  95.          if  bit 13 is set (tag & 0x2000), the tag data is a STRPTR, i.e.
  96.        a pointer to a null-terminated string.
  97.  
  98.          if  bit  14 is set (tag & 0x4000), the tag is considered a 'var-
  99.        parameter'  (e.g.  LONG *).  I.e.  the tag.data entry must contain
  100.        a  pointer  to  the  real  data,  which will be set/changed by the
  101.        called function.
  102.  
  103.          if both bits 13 and 14 are set ((tag & 0x6000)==0x6000), the tag
  104.        is a pointer to a string pointer which will be set/changed (STRPTR
  105.        *).
  106.  
  107.          if none of these bits is set, the data in most cases is a simple
  108.        integer parameter (e.g.  LONG or LONGBITS).
  109.  
  110. ums.library/--loginguide--
  111.  
  112.    PURPOSE
  113.  
  114.        Guidelines on a uniform login-procedure in UMS-applications
  115.  
  116.    GENERAL
  117.  
  118.        Shell- & Workbench-startup
  119.  
  120.        An application should take into account the command line arguments
  121.        (Shell) respectively Workbench tooltypes 'NAME', 'PASSWORD' and
  122.        'SERVER'. Concerning invokation from a Shell, the order of arguments
  123.        should match above example, with 'SERVER' declared a keyword
  124.        (resulting in a command template beginning
  125.        "NAME,PASSWORD,SERVER/K[,...]").
  126.  
  127.    SHELL
  128.  
  129.        Invocation from Shell:
  130.  
  131.        If the application is passed a questionmark as the only argument on
  132.        the command line (i.e. 'UMSapp ?'), it should return the template to
  133.        stdout and offer a prompt to have the user enter the desired options.
  134.        The user should be able to request additional help by responding to
  135.        the prompt with another questionmark. Additional help consists of
  136.        complete version information (at least a standard version template as
  137.        specified in "Amiga User Interface Styleguide" (pp. 110)) accompanied
  138.        by short help information.
  139.  
  140.        Technical realisation: DOS.ReadArgs() provides a standard means to
  141.        parsing the command line and behaves exactly in the above described
  142.        manner (it should therefore be used). Additional help text can be
  143.        passed to ReadArgs() by supplying a custom RDArgs structure as third
  144.        argument which holds a pointer to the text string in RDA_ExtHelp.
  145.        Refer to "The AmigaDOS Manual", Chapter 5, Basic Input and Output
  146.        Programming, Standard Command Line Parsing (pp. 181 as of the 3rd
  147.        edition)
  148.  
  149.    GUI
  150.  
  151.        Applications allowing login via GUI (graphical user interface):
  152.  
  153.        If 'NAME' is not specified at startup time, it must be entered to the
  154.        login window. Activate the name object.
  155.  
  156.        It is legal to pass an empty 'PASSWORD' as long as a name is
  157.        specified. Thus the empty password must attempt a login! If the user
  158.        passes the period (".") as 'PASSWORD', she desires to enter her
  159.        password to the login window. It should open with the password object
  160.        activated.
  161.  
  162.        If there is no 'SERVER' specified and the login window must be opened
  163.        due to the above guidelines, the server object should be filled with
  164.        the name of the default server (i.e. the server to which the user
  165.        would be going to log in to if she was not naming a different one
  166.        herself). The default server's name can be read from the ENV
  167.        $UMSSERVER. If the ENV does not exist, the default name is "default".
  168.        :-)
  169.  
  170.        A failed GUI login should be answered in a requester. After
  171.        confirmation the user should be presented with the unmodified login
  172.        window again as to correct her wrong inputs. Cancelling the requester
  173.        should result in terminating the application.
  174.  
  175.    NOTE
  176.  
  177.        Suggestions concerning these guidelines may be directed to Olaf Peters
  178.        <op@hb2.maus.de>
  179.  
  180. ums.library/--msg-format--                         ums.library/--msg-format--
  181.  
  182. ums.library/--messageformat--                   ums.library/--messageformat--
  183.  
  184.    NAME
  185.        UMS Message Format -- the universal format of UMS messages
  186.  
  187.    NOTE
  188.        Suggestions concerning these message format docs may be directed
  189.        to Christoph Viethen <cv@nostlgic.oche.de>.
  190.  
  191.    GENERAL
  192.        A message in the UMS message base is always defined by a list
  193.        of tags. This allows for easy extension as new tags may always
  194.        be defined later on.
  195.  
  196.        In one UMS message, each tag may occur only once.
  197.  
  198.    TEXT TAGS
  199.  
  200.        The first part of this Autodoc describes the format of the currently
  201.        defined TEXT-tags. Currently these tags include all information that
  202.        is site-independend and needed when transferring messages
  203.        between different systems.
  204.  
  205.        Except when explicitly stated otherwise, these tags are network-
  206.        independent. Drivers for all networks can and must understand them.
  207.  
  208.        A text-tag specifies a null-terminated string of any length.
  209.        All ASCII-characters are allowed. Unless something else is documented
  210.        for a specific tag, the standard Amiga charset (ISO 8859 Latin 1)
  211.        is used for 8-bit characters.
  212.  
  213.        Some of the text-tags are required for every message, others
  214.        are optional.
  215.  
  216.      0. UMSCODE_MsgText
  217.  
  218.        This contains the main 'text' of a message. Every message must
  219.        have this tag as it is usually the main information transported
  220.        by a message.
  221.  
  222.        Any information that does not belong to the original text must
  223.        not be put here. Even when a gateway between two different networks
  224.        puts information in the text, an UMS importer should - if possible -
  225.        extract this information and use or store it somewhere else.
  226.  
  227.        The text may be of any size, even empty.
  228.  
  229.        By using the new (V11) global ums.config item "Maxmsgsize" you
  230.        can set a size limit. Attempting to _write_ messages larger than this
  231.        into the message base will fail. (This limit does not affect the
  232.        size of messages already in the message base. If you, say, write
  233.        a message of 500K into the MB and then set "Maxmsgsize" to
  234.        300000 (bytes), there shouldn't be any problems when making read
  235.        accesses to this message.)
  236.  
  237.        Since some networks limit messages to a certain size, drivers for
  238.        these networks must be able to cope with this situation.
  239.  
  240.        Lines are delimited by the standard line delimiter (LF in the
  241.        current UMS implementation), no matter, what network the specific
  242.        messages originate from and what kind of line delimiters are
  243.        used there.
  244.  
  245.        Lines may be of any length, so it's up to the newsreader or exporter
  246.        to wrap lines if needed.
  247.  
  248.  
  249.      1. UMSCODE_FromName
  250.  
  251.        This is the name of the message's author. It's only the name and
  252.        NOT the address. This should be the REALNAME!
  253.  
  254.        If there is no realname, the username must be used or extracted
  255.        from the author's address.
  256.  
  257.        Every message must have this tag.
  258.  
  259.  
  260.      2. UMSCODE_FromAddress
  261.  
  262.        This is the author's net-address. The name needn't redundantly be
  263.        repeated  in this field, if it's already in UMSCODE_FromName.
  264.  
  265.        This tag must be empty or the tag must not be specified, if the author
  266.        is located on the local system. In every other case, this tag is
  267.        mandatory.
  268.  
  269.        Whenever possible, the address should be the user's real address
  270.        and not an encapsulated address or the address of a gateway. Thus
  271.        it may be necessary for importers to convert received addresses
  272.        to another network's format. The corresponding exporters, of
  273.        course, have to be able to re-convert these addresses. This makes
  274.        the use of gateways transparent to the user - one of UMS' most
  275.        important features. It saves the user from having to know and worry
  276.        about the formats of all the gateways himself.
  277.  
  278.        Since there are different networks with different formats of
  279.        addresses, it's neccessary to distinguish these different formats.
  280.        This is done by looking at the "tail" of the address. The following
  281.        formats are currently known:
  282.  
  283.           Identifier                          : network/format
  284.           ----------------------------------------------------
  285.           "@Fidonet"                          : FidoNet
  286.           ".maus"                             : MausNet
  287.           ".org", ".edu", ".UUCP", ".net",
  288.           ".de", .. [any valid usenet domain] : RFC
  289.           "@BIX"                              : BIX
  290.           "@Portal"                           : Portal
  291.  
  292.  
  293.        Important note:
  294.  
  295.           Under certain circumstances, other identifiers may be used:
  296.  
  297.           1) Small networks: Quite a few of them use adresses which
  298.           look like FidoNet-Adresses, but contain a different "zone
  299.           number". For practical reasons, messages from such networks
  300.           may be imported into the UMS message base using an identifier
  301.           other than "@Fidonet". So you may encounter addresses like e.g.
  302.           "21:100/1.0@Gernet" in the MB.
  303.  
  304.           2) There are special-purpose applications, like e.g. QWK im-/
  305.           exporters(?), which could use other kinds of identifiers not
  306.           contained in the above table.
  307.  
  308.        So programmers of UMS applications should keep the following in mind:
  309.  
  310.        Any UMS tool should be programmed in such a way that it does not
  311.        break if it encounters unknown network identifiers and/or formats.
  312.        In such cases, it should inform the user of the problem and behave
  313.        "neutrally", e.g. ignore the problematic message. UMS tools should
  314.        never rely on somewhat adventurous "address format guessing" methods.
  315.  
  316.        On the other hand, if you plan to write a tool that will import
  317.        messages into the MB with address formats different to the ones
  318.        mentioned in the above table, you are _strongly_ advised to contact
  319.        authors of other UMS applications, especially the developers of
  320.        the UMS im-/exporters, in order to avoid incompatibility problems
  321.        right from the start.
  322.  
  323.        Examples:
  324.  
  325.        a) Fidonet             2:2452/107.9@Fidonet
  326.                               2:242/53@Fidonet
  327.  
  328.        b) MausNet             AC2.maus
  329.                               MS.maus
  330.                               MK2.maus
  331.                               M.maus
  332.  
  333.        c) RFC                 maho@dfv.rwth-aachen.de
  334.                               marvin@tornado.oche.de
  335.                               in-info@individual.net
  336.                               postmaster@germany.uucp
  337.                               peterk@cbmger.de.so.commodore.com
  338.  
  339.  
  340.        Network-identifiers are NOT case-sensitive. Nevertheless, you
  341.        always should preserve case, as it might be needed by some
  342.        networks.
  343.  
  344.        Historical note:
  345.  
  346.           Some time ago, a special address format was used in the
  347.           german "Z-Netz", and its identifier was ".zer". That format
  348.           had a number of limitations and disadvantages, so a new
  349.           mail format called "ZConnect" was developed and now should
  350.           be used by all Z-Netz members. This new format no longer
  351.           needs any special address identifiers since it uses real RFC
  352.           addresses.
  353.           So the identifier ".zer" mentioned in the V10 version of
  354.           this documentation shouldn't be treated in a special way
  355.           by programs using ums.library any more.
  356.  
  357.  
  358.        Some examples for splitting addresses for 'Name' and 'Address':
  359.  
  360.        RFC:
  361.  
  362.        "Martin Horneffer <maho@umshq.dfv.rwth-aachen.de>"
  363.        -> name: "Martin Horneffer"
  364.           address: "maho@umshq.dfv.rwth-aachen.de"
  365.  
  366.        "horneff@pool.informatik.rwth-aachen.de (Martin Horneffer)"
  367.        -> name: "Martin Horneffer"
  368.           address: "horneff@pool.informatik.rwth-aachen.de"
  369.  
  370.        "horneff@pool.informatik.rwth-aachen.de"
  371.        -> name: "horneff"
  372.           address: "horneff@pool.informatik.rwth-aachen.de"
  373.  
  374.        FidoNet:
  375.  
  376.        "Martin Horneffer at 2:242/7.9"
  377.        -> name: "Martin Horneffer"
  378.           address: "2:242/7.9@Fidonet"
  379.  
  380.        "Joerg Gutzke at 2:242/7"
  381.        -> name: "Joerg Gutzke"
  382.           address: "2:242/7@Fidonet"
  383.  
  384.  
  385.      3. UMSCODE_ToName
  386.  
  387.        Name of the person the message is addressed to.
  388.  
  389.        Must be specified in all private messages ("e-mail") and is
  390.        optional in public messages ("news").
  391.  
  392.  
  393.      4. UMSCODE_ToAddress
  394.  
  395.        The addressed person's network address.
  396.  
  397.        Needed in private messages if the message has not yet reached
  398.        its destination. Must not be used when the mail is addressed to
  399.        a user on the local system.
  400.  
  401.        UMSCODE_ToName and UMSCODE_ToAddress have exactly the same format
  402.        as UMSCODE_FromName and UMSCODE_FromAddress.
  403.  
  404.        It should always be possible to reply to a private or public
  405.        message by using it's FromName and FromAddress as the new ToName
  406.        and ToAddress.
  407.  
  408.  
  409.      5. UMSCODE_MsgID
  410.  
  411.        A unique message ID in RFC-format. This is valid also for
  412.        non-RFC networks like FidoNet or MausNet!
  413.  
  414.        Every message must have such an ID. If there's no ID for a
  415.        message, the message base processor will create a new one
  416.        for this message. Never create message IDs on your own!
  417.  
  418.        Some example message ID's, just to give you an idea what IDs
  419.        from RFC and non-RFC systems may look like within UMS:
  420.  
  421.        2pocc6$qf2@Germany.EU.net
  422.        295@lyssa.owl.de                       (generated by RFC systems)
  423.  
  424.        91102312@p27.f107.n2452.z2.fidonet.org (generated by a Fido "point")
  425.        51515153@f7.n242.z2.fidonet.org        (generated by a  "non-point")
  426.  
  427.        199409281223.a27374@hro.maus.de        (generated in MausNet)
  428.  
  429.  
  430.      6. UMSCODE_CreationDate
  431.  
  432.        (Optional) date of creation, i.e.  when the message has been
  433.        written by the user.  May be in any format that is readable
  434.        by humans. AmigaDOS format (dd-mmm-yy hh:mm:ss) preferred.
  435.  
  436.        If not set, then the message base processor will use the
  437.        current date to create a date string in AmigaDOS format.
  438.  
  439.  
  440.      7. UMSCODE_ReceiveDate
  441.  
  442.        Obsolete. Don't use any more! As a replacement there is a tag
  443.        for a site-specific binary date.
  444.  
  445.  
  446.      8. UMSCODE_ReferID
  447.  
  448.        (Optional) message ID of the most recent message that is referred
  449.        to by the current message. Same format as 'MsgID'.
  450.  
  451.  
  452.      9. UMSCODE_Group
  453.  
  454.        Name of the message's newsgroup.
  455.  
  456.        Must be used for public messages only. Must not be used for
  457.        private mail. This tag is the only one that distinguishes private
  458.        from public messages.
  459.  
  460.        To avoid possible conflicts, the name of the network must be
  461.        prepended for non-usenet groupnames. Usenet groupnames, which
  462.        already are hierarchically ordered, stay as they are.
  463.  
  464.        E.g. "fidonet.AMIGA", "maus.ac.amiga", "comp.sys.amiga.misc".
  465.  
  466.        Only one group may be used in this field! Use 'Hardlinks' for
  467.        "crosspostings".
  468.  
  469.  
  470.      10. UMSCODE_Subject
  471.  
  472.        The (short) subject of the message. Required.
  473.  
  474.  
  475.      11. UMSCODE_Attributes
  476.  
  477.        (Optional) List of keywords. See ums.library/--attributes--
  478.  
  479.  
  480.      12. UMSCODE_Comments
  481.  
  482.        (Optional) all "header-"information, that belong to a message
  483.        and must be preserved, but don't fit to another text-tag. E.g.
  484.        all unknown RFC-header lines go here.
  485.  
  486.        The first line should specify the name of networks the message
  487.        comes from and the name (and perhaps version) of the importer.
  488.  
  489.  
  490.      13. UMSCODE_Organization
  491.  
  492.        (Optional) sender's organization or, in FidoNet, "Origin".
  493.  
  494.  
  495.      14. UMSCODE_Distribution
  496.  
  497.        (Optional) where/what the message should be distributed
  498.        to/by. Much like RFC-"Distribution:".
  499.  
  500.        Could e.g. be used to select which UMS-Exporter should export
  501.        the respective message if the ums.config is set accordingly.
  502.  
  503.  
  504.      15. UMSCODE_Folder
  505.  
  506.        (Written by receiver) The receiver of a private message may
  507.        use this field to store a short label in (not more than about
  508.        30 chars, not more than one line). This allows him to categorize
  509.        received messages. Newsreaders may allow to change that field for
  510.        private messages and then to use these categories or 'folders'
  511.        like 'groups' in public messages.
  512.  
  513.  
  514.      16. UMSCODE_FidoID
  515.  
  516.        This is specific to FidoNet.
  517.  
  518.        It should thus be ignored by all programs not specifically dealing
  519.        with FidoNet. It's used to keep the internal "^aMSGID" used within
  520.        FidoNet if it cannot be converted to 'MsgID'. This only applies to
  521.        messages that came from other networks and went to FidoNet through
  522.        some gateway.
  523.  
  524.  
  525.      17. UMSCODE_MausID
  526.  
  527.        This is specific to MausNet.
  528.  
  529.        It should thus be ignored by all programs not specifically dealing
  530.        with MausNet. It's used to store the internal MausNet-ID. It will
  531.        become superfluous when MausNet software learns to deal with real
  532.        Message-IDs.
  533.  
  534.  
  535.      18. UMSCODE_ReplyGroup
  536.  
  537.        (Optional) name of the group public replies ("follow-ups") should
  538.        go to. Ergo: Same purpose as "Followup-To:" in RFC1036.
  539.  
  540.        If not empty, newsreaders should copy this to the UMSCODE_Group field
  541.        of  the  new  message when writing a (public) follow-up.  Otherwise
  542.        keep the old UMSCODE_Group field.
  543.  
  544.        Exception to all this: If this field contains the string "poster",
  545.        this expresses the poster's wish to get a private reply. Newsreaders
  546.        and similar UMS tools should behave accordingly.
  547.  
  548.        Same format as for field UMSCODE_Group. Only one group allowed in
  549.        this field.
  550.  
  551.        If the author of the public message thinks that public replies
  552.        should go into several groups (as a "crossposting"), he may enter
  553.        a list of groups, seperated by commas, into this field.
  554.  
  555.  
  556.      19./20. UMSCODE_ReplyName/UMSCODE_ReplyAddress
  557.  
  558.        (Optional) name and address of the user private replies should go
  559.        to. Same purpose as "Reply-To:" in RFC822.
  560.  
  561.        If not empty, newsreaders should copy this to the 'ToName' and
  562.        'ToAddress'-field of the new message when writing a private reply.
  563.        Otherwise 'FromName' and 'FromAddress' should be used.
  564.  
  565.        Same format as for 'ToName' and 'ToAddress'.
  566.  
  567.  
  568.      21./22. UMSCODE_LogicalToName/UMSCODE_LogicalToAddress (V11)
  569.  
  570.        These fields are needed in UMS systems involved in automatic
  571.        mail distribution/forwarding, mailing lists e.g.
  572.  
  573.        Under such conditions, it may be necessary to differenciate between
  574.        "physical" and "logical" addresses. While physical addresses describe
  575.        the systems messages are indeed transported between, logical
  576.        addresses describe what origin and destination the original author
  577.        intended for his mail.
  578.  
  579.        If these fields are used, the fields UMSCODE_ToName and
  580.        UMSCODE_ToAddress contain the respective physical address.
  581.  
  582.        This field is optional - and usually not needed.
  583.  
  584.  
  585.      23. UMSCODE_FileName (V11)
  586.  
  587.        Well, this tag controls a still quite unknown and unimplemented
  588.        feature of UMS V11. :-)
  589.  
  590.  
  591.      24. UMSCODE_RFCMsgNum (V11)
  592.  
  593.        Private field for an NNTP daemon service or UUNEWS: emulator.
  594.  
  595.  
  596.      32. UMSCODE_FidoText
  597.  
  598.        This is specific to FidoNet.
  599.  
  600.        It should thus be ignored by all programs not specifically dealing
  601.        with FidoNet. It's used by FidoNet drivers to avoid loss of informa-
  602.        tion due to conversions of eol-delimiters or charsets.
  603.  
  604.  
  605.      33. UMSCODE_ErrorText
  606.  
  607.        This is private to the MBP and a very special utility called
  608.        'bounce-daemon'. It is used to transfer an error-text for writing
  609.        bounce-mails. No programs except of the 'bounce-daemon' should deal
  610.        with it.
  611.  
  612.  
  613.      34. UMSCODE_Newsreader
  614.  
  615.        (Optional) name and version of the tool the message was created with.
  616.        No specific format, but should be as small as possible. Not more
  617.        than one line.
  618.  
  619.  
  620.      35. UMSCODE_RfcAttr
  621.  
  622.        Private field for RFC exporters. The user can supply additional
  623.        information or hints to the exporter.
  624.  
  625.  
  626.      36. UMSCODE_FtnAttr
  627.  
  628.        Private field for FTN exporters. The user can supply additional
  629.        information or hints to the exporter.
  630.  
  631.  
  632.      37. UMSCODE_ZerAttr
  633.  
  634.        Private field for Z-Netz exporters. The user can supply additional
  635.        information or hints to the exporter.
  636.  
  637.  
  638.      38. UMSCODE_MausAttr
  639.  
  640.        Private field for Maus exporters. The user can supply additional
  641.        information or hints to the exporter.
  642.  
  643.  
  644.      127. UMSCODE_TempFileName (V11)
  645.  
  646.        This tag is related to UMSCODE_FileName and to a not-yet-implemented
  647.        feature of UMS V11.
  648.  
  649. ums.library/--attributes--                         ums.library/--attributes--
  650.  
  651. ums.library/UMSCannotExport                       ums.library/UMSCannotExport
  652.  
  653. ums.library/UMSDeleteMsg                             ums.library/UMSDeleteMsg
  654.  
  655. ums.library/UMSDupAccount                           ums.library/UMSDupAccount
  656.  
  657. ums.library/UMSErrNum                                   ums.library/UMSErrNum
  658.  
  659.    NAME
  660.        UMSErrNum -- Return the number of the last error
  661.  
  662.    SYNOPSIS
  663.        error = UMSErrNum(login)
  664.        D0                D2
  665.  
  666.        UMSError UMSErrNum(UMSAccount);
  667.  
  668.    FUNCTION
  669.        UMS functions usually return zero to indicate an error. When this
  670.        happens,  this  routine may be called to get a more specific error
  671.        code. By some means, this routine corresponds to an UMS login as
  672.        dos.library/IoErr() does to a DOS-process.
  673.  
  674.        Possible UMS errors are:
  675.  
  676.         0      : No error at all, the last UMS function call was
  677.                  successful.
  678.  
  679.         100-199: A slight  error. The last functions call was not
  680.                  successful, but may succeed if some slight changes
  681.                  will be made to its parameters.
  682.  
  683.         200-299: A real error. The last function call was not successful
  684.                  at all and should not be retried.
  685.  
  686.         300-   : A severe error concerning the whole system, e.g.
  687.                  the server has terminated. A program receiving such
  688.                  an error is recommended to UMSLogout() and terminate
  689.                  as soon as possible.
  690.  
  691.    INPUTS
  692.        login - Handle as returned by UMSLogin() or UMSRLogin()
  693.  
  694.    RESULT
  695.        error - Error number
  696.  
  697.    SEE ALSO
  698.        UMSErrTxt()
  699.  
  700. ums.library/UMSErrTxt                                   ums.library/UMSErrTxt
  701.  
  702.    NAME
  703.        UMSErrTxt -- Return a string describing the last error
  704.  
  705.    SYNOPSIS
  706.        text = UMSErrTxt(login)
  707.        D0               D2
  708.  
  709.        STRPTR UMSErrTxt(UMSAccount);
  710.  
  711.    FUNCTION
  712.        When an UMS function fails and/or UMSErrNum() returns a nonzero
  713.        value,  you  should  use  this routine to get a brief English
  714.        description of the last error.
  715.  
  716.        Interactive  programs should  display  this  text  to the user.
  717.        Non-interactive programs should use this text in their logfile.
  718.  
  719.    INPUTS
  720.        login - Handle as returned by UMSLogin() or UMSRLogin()
  721.  
  722.    RESULT
  723.        text - Pointer to a constant string
  724.  
  725.    NOTES
  726.        This is similiar to dos.library/Fault(), but it doesn't copy any
  727.        string, it just returns a pointer.
  728.  
  729.        You may NEVER change the string returned by UMSErrTxt()!
  730.  
  731.    SEE ALSO
  732.        UMSErrNum(), UMSErrTxtFromNum()
  733.  
  734. ums.library/UMSErrTxtFromNum                     ums.library/UMSErrTxtFromNum
  735.  
  736.    NAME
  737.        UMSErrTxtFromNum -- Return a string describing the last error
  738.  
  739.    SYNOPSIS
  740.        text = UMSErrTxtFromNum(error)
  741.        D0                      D2
  742.  
  743.        STRPTR UMSErrTxtFromNum(UMSError);
  744.  
  745.    FUNCTION
  746.        When an UMS function not related to an UMSAccount returns an nonzero
  747.        value, you should use this routine to get a brief English description
  748.        of the last error.
  749.        Interactive programs should display this text to the user.
  750.        Non-interactive programs should use this text in their logfile.
  751.  
  752.    INPUTS
  753.        error - UMS error code
  754.  
  755.    RESULT
  756.        text - Pointer to a constant string
  757.  
  758.    NOTES
  759.        This is similiar to dos.library/Fault(), but it doesn't copy any
  760.        string, it just returns a pointer.
  761.  
  762.        You may NEVER change the string returned by UMSErrTxtFromNum()!
  763.  
  764.    SEE ALSO
  765.        UMSErrTxt()
  766.  
  767. ums.library/UMSExportedMsg                         ums.library/UMSExportedMsg
  768.  
  769.    NAME
  770.        ExportedMsg -- Mark a message as being successfully exported.
  771.  
  772.    SYNOPSIS
  773.        ExportedMsg( login, msgNum )
  774.                      D2      D3
  775.  
  776.        VOID ExportedMsg( LONG, LONG );
  777.  
  778.    FUNCTION
  779.          Tells  the  MBP  that  a message has been successfully exported.
  780.        The  MBP  uses  this  information  to prevent other exporters from
  781.        wrongly  exporting  this message a second time or writing a bounce
  782.        message.
  783.  
  784.          Every  exporter that exports a message from the local UMS system
  785.        to  any  other system or network MUST call either ExportedMsg() or
  786.        CannotExport()  for  each message it has processed.  This is valid
  787.        for  private  messages as well as for public messages (news).  The
  788.        MBP will decide what has to be done in any of these cases.
  789.  
  790.    INPUTS
  791.        msgNum - Number of the exported message.
  792.  
  793.    NOTES
  794.          This function may only be called by exporters.
  795.  
  796.    SEE ALSO
  797.        CannotExport()
  798.  
  799. ums.library/UMSFreeConfig                           ums.library/UMSFreeConfig
  800.  
  801.    NAME
  802.  
  803.        UMSFreeConfig - Free a string returned by UMSReadConfig()
  804.  
  805.    SYNOPSIS
  806.  
  807.        UMSFreeConfig( login, string)
  808.                        D2      D3
  809.  
  810.        void UMSFreeConfig( LONG, STRPTR );
  811.  
  812.    FUNCTION
  813.  
  814.        Frees the buffer allocated for a string and returned by
  815.        UMSReadConfig(). After 'UMSFreeConfig(string)', 'string' will no
  816.        longer be valid.
  817.  
  818.    INPUTS
  819.  
  820.        login  - Handle as returned by UMSLogin() or UMSRLogin()
  821.        string - string to be freed as returned by UMSReadConfig()
  822.  
  823.    SEE ALSO
  824.  
  825.        UMSReadConfig()
  826.  
  827. ums.library/UMSLog                                         ums.library/UMSLog
  828.  
  829.    NAME
  830.        UMSLog -- Write an entry to the global UMS logfile
  831.  
  832.    SYNOPSIS
  833.        UMSLog(login, level, format, ...)
  834.               D2     D4     D5      D6
  835.  
  836.        void UMSLog(UMSAccount, LONG, STRPTR, ... );
  837.  
  838.        UMSVLog(login, level, format, args)
  839.                 D2    D4      D5     D6
  840.  
  841.        void UMSVLog(UMSAccount, LONG, STRPTR, APTR);
  842.  
  843.    FUNCTION
  844.        Write a short message to the UMS logfile, doing printf()-style
  845.        formatting on supplied parameters.
  846.  
  847.        Rather than creating its own logfile, an application should use
  848.        this function to report its actions and/or errors. This makes it
  849.        easier for the user to get an overview on what is happening in
  850.        his system - he only has to look in ONE logfile.
  851.  
  852.        UMSLog()  uses  a 'level' parameter to decide whether a message
  853.        should actually be written to the logfile or be ignored. The lower
  854.        this number, the more important is the message. Choose it as follows:
  855.  
  856.          1-4: An ERROR.  1 = very fatal error, 4 = recoverable error.
  857.          5-7: General information or report.
  858.          8-9: Information that is not useful for normal operation, but
  859.               used for debugging purposes.
  860.  
  861.        Of course messages with high level values should appear more
  862.        frequently than those with low level values.
  863.  
  864.    INPUTS
  865.        login  - Handle as returned by UMSLogin() or UMSRLogin()
  866.        level  - Number between 1 and 9
  867.        format - printf()-style format string. See exec.library/RawDoFmt()
  868.                 for more information on formatting.
  869.        args   - Arguments for the format string
  870.  
  871.    SEE ALSO
  872.        exec.library/RawDoFmt()
  873.  
  874. ums.library/UMSLogin                                     ums.library/UMSLogin
  875.  
  876.    NAME
  877.        UMSLogin -- Obtain a login for access to the default message base
  878.  
  879.    SYNOPSIS
  880.        login = UMSLogin(user, passwd)
  881.        D0               D2    D3
  882.  
  883.        UMSAccount UMSLogin(STRPTR, STRPTR);
  884.  
  885.    FUNCTION
  886.        This function does the same as UMSRLogin(), but you cannot specify
  887.        the message base. The default message base will be used instead.
  888.  
  889.        New programs shouldn't use this function. Use UMSRLogin() so that
  890.        the user may specify a message base.
  891.  
  892.    INPUTS
  893.        user   - Name or 'alias' of an user
  894.        passwd - The password of the user. A pointer to the null-string is
  895.                 allowed, NULL itself isn't.
  896.  
  897.    RESULT
  898.        login  - Handle number if successful or Zero on failure
  899.  
  900.  
  901.    EXAMPLE
  902.        UMSAccount login = UMSLogin("SysOp", "secret");
  903.  
  904.    NOTE
  905.        Never forget to call UMSLogout()!
  906.  
  907.        New programs shouldn't use this function. Use UMSRLogin() so that
  908.        the user may specify a message base.
  909.  
  910.    SEE ALSO
  911.        UMSLogout(), UMSRLogin()
  912.  
  913. ums.library/UMSLogout                                   ums.library/UMSLogout
  914.  
  915.    NAME
  916.        UMSLogout -- Close a login and free its resources
  917.  
  918.    SYNOPSIS
  919.        UMSLogout(login)
  920.                  D2
  921.  
  922.        void UMSLogout(UMSAccount);
  923.  
  924.    FUNCTION
  925.        Close a login obtained with UMSRLogin() and free all related
  926.        resources.
  927.  
  928.    INPUTS
  929.        login - Handle as returned by UMSLogin() or UMSRLogin()
  930.  
  931.    SEE ALSO
  932.        UMSLogin(), UMSRLogin()
  933.  
  934. ums.library/UMSMatchConfig                         ums.library/UMSMatchConfig
  935.  
  936. ums.library/UMSReadConfig                           ums.library/UMSReadConfig
  937.  
  938.    NAME
  939.        UMSReadConfig -- Read an element from UMS' configuration.
  940.  
  941.    SYNOPSIS
  942.        string = UMSReadConfig( login, tags )
  943.          D0                     D2     D3
  944.  
  945.        STRPTR UMSReadConfig( LONG, struct TagIten * );
  946.  
  947.        string = UMSReadConfigTags( login, tag1, ... )
  948.  
  949.        STRPTR UMSReadConfigTags( LONG, ULONG, ... );
  950.  
  951.  
  952.    FUNCTION
  953.        Read an object from UMS' configuration.
  954.  
  955.        Whenever possible, applications should use the UMS configuration
  956.        (as stored in the file 'ums.config' in the directory of the
  957.        message-base) and the supplied functions UMSReadConfig() and
  958.        UMSWriteConfig() instead of own special config-files.
  959.  
  960.        A 'config-string' is a null-terminated string identified by an
  961.        unique name. Similar to shell- and environment-variables
  962.        config-strings can be global (same for all users) or local (only
  963.        visible to a certain user).
  964.  
  965.        Other config-objects are 'users' (with aliases and local strings),
  966.        'akas' and 'netgroups'.
  967.  
  968.        In order not to mix up config-strings of different applications,
  969.        their names should have the id of the application and a dot
  970.        prepended. E.g. "fido.outbound", "fido.inbound", "uucp.uuspool",
  971.        "IntuiNews.QuoteChars.foo.bar", "ConfUMS.ForceDelete" etc.
  972.  
  973.        Names without a dot (".") are considered private strings of the
  974.        MBP, e.g. "READACCESS", "WRITEACCESS".
  975.  
  976.        Names for config elements are case-insensitive.
  977.  
  978.        This function buffers the returned string until it is freed with
  979.        UMSFreeConfig() or (UMSLogout()).
  980.  
  981.    INPUTS
  982.        The following tags are allowed:
  983.  
  984.          CfgGlobalOnly         : (none)
  985.        read just global config-elements, ignore local ones.
  986.  
  987.          CfgUser               : STRPTR
  988.        read config elements local to another user. You must specify the
  989.        name of the other user here. This contradicts CfgGlobalOnly (see
  990.        above)!
  991.  
  992.          CfgLockVar        : LONG                      (V11)
  993.        using this tag you may preserve the config
  994.        string from being modified by another login, i.e. another UMS
  995.        program. Set the tag's data to 1 if you want to do so, otherwise
  996.        use 0 (or do not use this tag) to not lock the variable. Be
  997.        careful to unlock the variable if you do not need it anymore using
  998.        UMSWriteConfig()'s tags CfgUnlockVar! This tag is useful only in
  999.        conjunction with CfgName (see below).
  1000.  
  1001.          CfgQuoted               : LONG              (V11)
  1002.        read the variable in quoted format, as used in "ums.config". This
  1003.        enables you to mix the variable's data with macros. Set the tag's
  1004.        data to 1 if you want to use the quoted format, otherwise set it
  1005.        to 0 (or do not use this tag).
  1006.  
  1007.  
  1008.        The following tags are mutually exclusive. Use exactly one of
  1009.        them.
  1010.  
  1011.        The CfgNext-tags allow you to scan all the existing elements of
  1012.        one type and do all work in the same manner: On first invocation
  1013.        you set the tag's data to NULL and get the first element. With
  1014.        every further call, you set it to what has been returned on the
  1015.        previous call. When NULL is returned, you're done.
  1016.  
  1017.          CfgName               : STRPTR
  1018.        read a config-string with given name.
  1019.  
  1020.          CfgUserName           : STRPTR
  1021.        get the 'realname' for a user with a given alias.
  1022.  
  1023.          CfgNextVar            : STRPTR
  1024.        get the name of the next config variable. This tag may be combined
  1025.        with tag CfgGlobalOnly or tag CfgUser (see above).
  1026.  
  1027.          CfgNextAlias          : STRPTR              (V11)
  1028.  
  1029.        get the next alias. This tags may be combined with CfgUser (see
  1030.        above)
  1031.  
  1032.          CfgNextUser           : STRPTR              (V11)
  1033.        get the 'realname' of the next user.
  1034.  
  1035.          CfgNextExporter       : STRPTR              (V11)
  1036.        get the name of the next export.
  1037.  
  1038.          CfgNextGroup          : STRPTR
  1039.  
  1040.        get the name of the next netgroup. Any number of groupnames may be
  1041.        configured as identical 'netgroups'. Use this tag to scan all
  1042.        netgroups, to scan their members use CfgNextGroupMember (see
  1043.        below).
  1044.  
  1045.          CfgNextGroupMember    : STRPTR              (V11)
  1046.        get the name of the next member of a specific netgroup. Using this
  1047.        tag repeatedly you can cycle trough all groups belonging to the
  1048.        same netgroup. Members of netgroups are organized in a circular
  1049.        structure, so you'll have to compare the original string with
  1050.        every result to determine whether you're done. NULL is returned
  1051.        only if the given string doesn't indicate a valid netgroup-member.
  1052.  
  1053.    RESULT
  1054.        string - a pointer to the desired config element or NULL.
  1055.  
  1056.    SEE ALSO
  1057.        UMSFreeConfig(), UMSWriteConfig()
  1058.  
  1059. ums.library/UMSReadMsg                                 ums.library/UMSReadMsg
  1060.  
  1061.    NAME
  1062.        UMSReadMsg -- Read (parts of) a message.
  1063.  
  1064.    SYNOPSIS
  1065.        success = UMSReadMsg( login, tags )
  1066.          D0                   D2     D3
  1067.  
  1068.        BOOL UMSReadMsg( LONG, struct TagItem * );
  1069.  
  1070.        success = UMSReadMsgTags( login, tag1, ... )
  1071.  
  1072.        BOOL UMSReadMsgTags( LONG, ULONG, ... );
  1073.  
  1074.    FUNCTION
  1075.          Read a message or any parts of it.
  1076.  
  1077.    INPUTS
  1078.          The following tags are allowed:
  1079.  
  1080.          RMsgNum               : LONG
  1081.                specify which msg to read. This tag MUST be used!
  1082.  
  1083.          RHeaderLength         : LONG *
  1084.                you have to pass a pointer to a LONG here.  This LONG will
  1085.        be  set  to  the length of the message-header in bytes.  I.e.  the
  1086.        length  of all text-fields considered to belong to the 'header' of
  1087.        a message.
  1088.  
  1089.          RTextLength           : LONG *
  1090.                like  RHeaderLength,  but  the length of the message-text.
  1091.        These are all other fields.
  1092.  
  1093.          RMsgDate              : LONG *
  1094.                the  date the message has been written to the message-base
  1095.        (also  referred  to  as  the  'receive-date').  In AmigaDOS Format
  1096.        (seconds since 1.1.1978).
  1097.  
  1098.          RChainUp,
  1099.          RChainDn,
  1100.          RChainLt,
  1101.          RChainRt              : LONG *
  1102.                reply-chaining.   Since  a  message  can only refer to one
  1103.        other  (older)  message,  but have multiple other (newer) messages
  1104.        referring  to  it, a tree is built out of this 'comment-chaining'.
  1105.        ChainUp  points to the referred message.  ChainDn points to one of
  1106.        the messages that comment on the current one.  ChainLt and ChainRt
  1107.        point to other messages which share the same ChainUp.
  1108.                The  LONG  you  supply a pointer to in the tag's data will
  1109.        either  be  set  to  zero  (when there is no such chain) or to the
  1110.        number of a message.
  1111.  
  1112.          RGlobalFlags          : LONGBITS *
  1113.                global  flags  for  this message.  In the MB every message
  1114.        has  exactly one set of global flags.  See <ums.h> for the meaning
  1115.        of these flags.
  1116.  
  1117.          RUserFlags            : LONGBITS *
  1118.                user-flags for this message.  Every user of the MB has one
  1119.        set  of user-flags for each message.  See <ums.h> for the fixed or
  1120.        suggested meanings of these flags.
  1121.  
  1122.          RLoginFlags           : LONGBITS *
  1123.                login-flags  for  this message.  Every login has a private
  1124.        set  of  flags  for  each  message.   In  contrast  to  global  or
  1125.        user-flags,  login-flags  are NOT saved and vanish on UMSLogout().
  1126.        They are set to zero on UMSLogin().
  1127.  
  1128.          RHardLink,
  1129.          RSoftLink             : LONG *
  1130.                a  pointer  to another link in the circular linked list of
  1131.        linked  messages.   Zero  if  a  real  message  (no  link).  Since
  1132.        message-links can be either hard or soft, but not both at the same
  1133.        time, only one of these can be non-zero.
  1134.  
  1135.          RDateStyle            : LONG
  1136.                use  this  tag and set its data to 1 if you want to get an
  1137.        old-style  'receive-date'.   Don't use this tag or set its data to
  1138.        zero otherwise.
  1139.  
  1140.          RMsgText, ..
  1141.          RMsgText + 127        : STRPTR *
  1142.                tell  UMS  that  you want to read the specified text-field
  1143.        and  supply a place for a pointer to it.  This will be set to NULL
  1144.        if  the  field  doesn't  exist  or  you're not allowed to read it.
  1145.  
  1146.          RTextFields           : UMSMsgTextFields
  1147.                if  you  supply  a pointer to an array of 128 STRPTR here,
  1148.        it  will  be  set  to  the read text-fields.  Useful for reading a
  1149.        whole  message  without  having to specify a tag for each possible
  1150.        text-field.
  1151.  
  1152.          RReadHeader           : (none)
  1153.                tell  UMS  that you want to read all header-field.  Useful
  1154.        in combination with RTextFields only.
  1155.  
  1156.          RReadAll              : (none)
  1157.                tell  UMS  that  you  want  to read the message-text, too.
  1158.        Useful in combination with RTextFields only.
  1159.  
  1160.  
  1161.        The following tag was not implemented in ums.library until V9.70 !
  1162.  
  1163.          RIDStyle              : LONG
  1164.                choose  the  style  of  local  message IDs.  There are two
  1165.        possible  formats of 'local' message IDs (= the IDs created by the
  1166.        local system):
  1167.  
  1168.                a)  a  simple  decimal  number that is unique on the local
  1169.        system
  1170.                b)  this  decimal  number  followed by "@" and the domain-
  1171.        address of the local system.  This conforms with RFC822/1036.
  1172.  
  1173.                Old  (obsolete) Version of ums.library (< V9.70) still use
  1174.        format a), but since V9.70 versions use format b) in order to make
  1175.        things cleaner and make life easier for exporters.  With format a)
  1176.        exporters  must  append the domain-address to IDs themselves, with
  1177.        format b) they needn't care about whether an ID is local or not.
  1178.  
  1179.                As  an  interim  solution  this  tag allows to specify the
  1180.        desired  format.  Its  data set to 1 forces format a), 0 (default)
  1181.        forces format b).
  1182.  
  1183.          RNoUpdate              : LONG
  1184.                when  reading  its  message-text,  a  message  is  usually
  1185.        updated  by having its 'Old'-flag set in your user-status.  If you
  1186.        don't  want  the Old-flag to be set, use this tag and set its data
  1187.        to 1.
  1188.  
  1189.    RESULT
  1190.        success  - whether your attempt to read the message was successful
  1191.                   or not.
  1192.  
  1193.    NOTES
  1194.          The  message  will  be  buffered,  so you can easily use all the
  1195.        returned  STRPTRs.   You  have  to  use  FreeUMSMsg()  to free the
  1196.        buffers allocated for a certain message.
  1197.  
  1198.          An  user or exporter usually wants to read a single message only
  1199.        once.
  1200.          To  make  this  easy, ReadUMSMsg() checks whether the user reads
  1201.        the 'MsgText' of a message, and, if so, sets the 'Old'-Flag in the
  1202.        users status if it wasn't already set.
  1203.          So  the  user (or exporte) only needs to ask for this flag to be
  1204.        unset  when  using  'UMSSearch()'  before  'ReadUMSMsg()' and will
  1205.        automatically avoid reading the same message a second time.
  1206.  
  1207.    SEE ALSO
  1208.        FreeUMSMsg(), UMSSearch()
  1209.  
  1210.  
  1211. ums.library/UMSRLogin                                   ums.library/UMSRLogin
  1212.  
  1213.    NAME
  1214.        UMSRLogin -- Obtain a login for access to a message base
  1215.  
  1216.    SYNOPSIS
  1217.        login = UMSRLogin(server, user, passwd)
  1218.        D0                D2      D3    D4
  1219.  
  1220.        UMSAccount UMSRLogin(STRPTR, STRPTR, STRPTR);
  1221.  
  1222.    FUNCTION
  1223.        This function is used to get access to an UMS message base. If
  1224.        necessary the UMSServer is launched first. ...
  1225.  
  1226.        This function returns a handle which is used internally to track
  1227.        and remember the resources associated with each login. If an user
  1228.        tries to login multiple times this handle will be different each
  1229.        time. A login may be used only by the process which created it
  1230.        UMSRLogin(). Zero on failure, any other value indicates success.
  1231.  
  1232.    INPUTS
  1233.        server - Name of the message base
  1234.        user   - Name or 'alias' of an user
  1235.        passwd - The password of the user. A pointer to the null-string is
  1236.                 allowed, NULL itself isn't.
  1237.  
  1238.    RESULT
  1239.        login  - Handle number if successful or Zero on failure
  1240.  
  1241.  
  1242.    EXAMPLE
  1243.        UMSAccount login = UMSRLogin("TestServer", "SysOp", "secret");
  1244.  
  1245.    NOTE
  1246.        Never forget to call UMSLogout()!
  1247.  
  1248.        Use this function instead of UMSLogin() for new programms.
  1249.  
  1250.    SEE ALSO
  1251.        UMSLogin(), UMSLogout()
  1252.  
  1253. ums.library/UMSSearch                                   ums.library/UMSSearch
  1254.  
  1255.    NAME
  1256.        UMSSearch -- Search a message from the MB.
  1257.  
  1258.    SYNOPSIS
  1259.        msgNum = UMSSearch( login, tags )
  1260.          D0                 D2     D3
  1261.  
  1262.        LONG UMSSearch( LONG, struct TagItem * );
  1263.  
  1264.        msgNum = UMSSearchTags( login, tag1, ... )
  1265.  
  1266.        LONG UMSSearchTags( LONG, ULONG, ... );
  1267.  
  1268.    FUNCTION
  1269.          Search  the  first  (or  next)  message in the MB that fullfills
  1270.        certain criteria.
  1271.  
  1272.          When  you  want  to  read  certain  messages  from the MB, it is
  1273.        recommended that you first select these  messages with UMSSelect()
  1274.        and  then  alternately  use  UMSSearch()  and ReadUMS() to get all
  1275.        these messages.
  1276.  
  1277.    INPUTS
  1278.          Allowed tags:
  1279.  
  1280.          SearchLast            : LONG
  1281.                specify  the  last message NOT to search.  This tag allows
  1282.        you  to  cycle  trough all messages fullfilling the same criteria:
  1283.        set this to zero and invoke UMSSearch() the first time.  Check the
  1284.        result  and  if  it's  not  zero,  put  it  in this tag and invoke
  1285.        UMSSearch() again.  Repeat this until it returns zero.
  1286.  
  1287.          SearchDirection       : LONG
  1288.                set  the  search  direction.   1  means search forward (to
  1289.        higher  numbers), -1 means search backwards (to lower numbers) and
  1290.        0  lets  the  MBP  decide  what  sequence to use.  This needn't be
  1291.        exactly  forwards  or  backwards.   It  might  be  in a completely
  1292.        different order.
  1293.                When you don't depend on a certain search-direction, use 0
  1294.        or omit this tag.
  1295.  
  1296.          SearchGlobal          : (none)
  1297.          SearchLocal           : (none)
  1298.          SearchUser            : STRPTR
  1299.          SearchMask            : LONGBITS
  1300.          SearchMatch           : LONGBITS
  1301.                search   for   a   matching  status;  like  SelReadGlobal,
  1302.        SelReadLocal, SelReadUser, SelMask and SelMatch with UMSSelect().
  1303.  
  1304.          WMsgText, ..
  1305.          WMsgText + 127        : STRPTR
  1306.                search  for a matching text; as for UMSSelect().  Only one
  1307.        field can be searched for at a time.
  1308.  
  1309.          SearchQuick           : (none)
  1310.                Enable 'quick-search'.  This must be combined with exactly
  1311.        one  of  WMsgText+1  ..  WMsgText+31.  quick-searches are possible
  1312.        for  exact  string  searches  only, they must not be combined with
  1313.        patterns and they are only possible for fields that have an index.
  1314.                They  don't  guarantee  that  the returned message's field
  1315.        actually  matches  the  given  string,  altough  mistakes are very
  1316.        unlikely.
  1317.                But they are fast! (see NOTES below)
  1318.  
  1319.          SearchPattern         : LONG
  1320.                indicate whether the string to be searched for is an exact
  1321.        string  (0), an AmigaDOS pattern (1) or UMS should try to find out
  1322.        (2).
  1323.  
  1324.    RESULT
  1325.        msgNum - numer of a/the searched message; zero if not found.
  1326.  
  1327.    NOTES
  1328.          Although  LONGBITS  are  used  in  the  definition,  the current
  1329.        implementation only uses/supports the lower 16 bits.
  1330.  
  1331.          Performance:   when  searching  for  strings, different calls to
  1332.        UMSSearch()  may  significantly  vary  in  performance.  There are
  1333.        three general possibilities:
  1334.  
  1335.          1) quick-searches:
  1336.        very fast, no access to the hard-disk needed (once the right index
  1337.        is  loaded  into  memory).   Only  possible  if  tag 'SearchQuick'
  1338.        specified.
  1339.  
  1340.          2) indexed searches:
  1341.        fast,  in most cases only one, short access to hd is needed; a few
  1342.        more   in   really   bad  situations.   If  the  'header'-file  is
  1343.        sufficiently  buffered, no accesses to the hd may occur.  Possible
  1344.        if searching for exact strings in indexed fields.
  1345.  
  1346.          3) other searches (non-indexed or patterns):
  1347.        slow,  many  data  will  have  to  be  read from hd.  If the field
  1348.        searched for is in the 'header'-file and it's heavily buffered, no
  1349.        accesses  to  the  hd  may  occur.   Nevertheless  the search will
  1350.        consume much CPU-time.
  1351.  
  1352.          Search for status!!!
  1353.  
  1354.          Searching for a matching status only (i.e.  not searching for a
  1355.        string) is always very fast.
  1356.  
  1357.          When doing non-indexed- or pattern-search, combine with status
  1358.        to reduce the amount of data to be searched through!
  1359.  
  1360.    SEE ALSO
  1361.        UMSSelect(), ReadUMS(), <ums.h>
  1362.  
  1363.  
  1364. ums.library/UMSSelect                                   ums.library/UMSSelect
  1365.  
  1366.    NAME
  1367.        UMSSelect -- Select messages.
  1368.  
  1369.    SYNOPSIS
  1370.        count = UMSSelect( login, tags )
  1371.         D0                 D2     D3
  1372.  
  1373.        LONG UMSSelect( LONG, struct TagItem * );
  1374.  
  1375.        count = UMSSelectTags( login, tag1, ... )
  1376.  
  1377.        LONG UMSSelectTags( LONG, ULONG, ... );
  1378.  
  1379.    FUNCTION
  1380.          Select  messages  in  the  MB according to various criteria.  To
  1381.        'select'  here means to set or unset some flags, which then can be
  1382.        used by UMSSearch(), stored or transferred to another user.
  1383.  
  1384.          UMSSelect()  can  only  do  one operation upon every invocation.
  1385.        An  operation  usually  looks  for  all messages that fullfill the
  1386.        specified criteria and then selects them in a specified way.
  1387.  
  1388.          When  you  want  to  select  messages  by  different,  logically
  1389.        combined criteria, you may need to call UMSSelect() more than once
  1390.        and  use  some  temporary  flags.  However, very few calls to this
  1391.        functions usually should suffice.
  1392.  
  1393.    INPUTS
  1394.  
  1395.          The  following  tags  control  the selection of messages.  Thus,
  1396.        they somehow specify the 'output' of the select operation.
  1397.  
  1398.          SelWriteGlobal        : (none)
  1399.                manipulate global flags on the selected messages.
  1400.  
  1401.          SelWriteLocal         : (none)
  1402.                manipulate your local login-flags.
  1403.  
  1404.          SelWriteUser          : STRPTR
  1405.                manipulate another user's user-flags. You must specify the
  1406.        users name (or alias).
  1407.  
  1408.          SelWriteGlobal,   SelWriteLocal   and  SelWriteUser  are  mutual
  1409.        exclusive  --  you can  manipulate  only one flag-table at a time.
  1410.        When  specifying  none  of  these  tags,  your  user-flags will be
  1411.        manipulated as default.
  1412.  
  1413.          SelSet,
  1414.          SelUnset              : LONGBITS
  1415.                on  each selected message the 'SelUnset' flags are cleared
  1416.        and then the 'SelSet' flags are set.
  1417.        ['status = (status & ~unset) | set;']
  1418.                When writing global- or user-flags, you are not allowed to
  1419.        manipulate all possible flags.  See <ums.h> for protected flags.
  1420.  
  1421.  
  1422.          The  following  tags control what and how messages are selected,
  1423.        the 'input' and 'modes' of the select operation.
  1424.  
  1425.          SelStart,
  1426.          SelStop               : LONG
  1427.                Limit  the number of messages to be processed.  The select
  1428.        operation  will start with the message indicated by 'SelStart' and
  1429.        stop  before  the  'SelStop'  message.   In  other words, start is
  1430.        included  and  stop  is  excluded.
  1431.                (0 < start <= messages to be processed < stop)
  1432.                This  was different and partly buggy in MBP versions prior
  1433.        to V10.16.
  1434.                If  no  'SelStart' is specified, the operation starts with
  1435.        the  first  message;  if  no 'SelStop' is specified, the operation
  1436.        stops at the last existing message.
  1437.  
  1438.  
  1439.          The following seven operations are mutually exclusive:
  1440.  
  1441.        1) select by status
  1442.  
  1443.          SelReadGlobal         : (none)
  1444.          SelReadLocal          : (none)
  1445.          SelReadUser           : STRPTR
  1446.                like   SelWriteGlobal,  SelWriteLocal,  SelWriteUser,  but
  1447.        specifys  which  flags to look at.  Again, your user-flags are the
  1448.        default.
  1449.  
  1450.          SelMask,
  1451.          SelMatch              : LONGBITS
  1452.                specify  a  mask and a match.  If (status & mask) == match
  1453.        [status * mask = match], the message will be selected.
  1454.  
  1455.          SelParent             : (node)
  1456.               with   this   tag   specified,   each   message's  'parent'
  1457.        (reference;  ->  reply-chaining)  will be inspected instead of its
  1458.        own status.
  1459.  
  1460.        2) select by date
  1461.  
  1462.          SelDate               : LONG
  1463.                the  messages'  dates  are compared with the supplied date
  1464.        (in  seconds  since  1.1.1978)  and  only the younger ones will be
  1465.        selected.
  1466.  
  1467.        4) select a tree
  1468.  
  1469.          SelTree               : LONG
  1470.                you  must specify  the number of a message here.  Then all
  1471.        messages being in the same reply-tree will be selected.
  1472.  
  1473.        5) select a sub-tree
  1474.  
  1475.          SelSubTree            : LONG
  1476.                like  SelTree,  but  only  the  subtree  (the one with the
  1477.        specified message as its root) is selected.
  1478.  
  1479.        6) select a single message
  1480.  
  1481.          SelMsg                : LONG
  1482.                select only the specified message.
  1483.  
  1484.        7) select by text
  1485.  
  1486.          WMsgText, ..
  1487.          WMsgText + 127        : STRPTR
  1488.                when  you  specify one of these tags, the function selects
  1489.        all  messages  which  have  the  supplied  string in the specified
  1490.        field.  The strings are compared case-INsensitive.
  1491.  
  1492.          SelQuick              : (none)
  1493.                when  this tag is specified, 'quick-search' is enabled for
  1494.        selecting  texts.  This means that only some CRCs on the texts are
  1495.        compared.   This  makes  it  possible  to  select  also some wrong
  1496.        messages.   Yet,  due to the usage of 32-bit CRCs, the probability
  1497.        of  selecting  wrong  messages  is  VERY low, you most likely will
  1498.        never experience this case.
  1499.                As  'quick-search'  does  not usually need to access mass-
  1500.        storage, it is VERY FAST.
  1501.  
  1502.    RESULT
  1503.        count - how many messages have been selected.  Zero, when no
  1504.                message has been selected or an error has occured.
  1505.  
  1506.    EXAMPLE
  1507.          See SelectMail.c for examples on how to use this function.
  1508.  
  1509.    NOTES
  1510.          Although  LONGBITS  are  used  in  the  definition,  the current
  1511.        implementation only uses/supports the lower 16 bits.
  1512.  
  1513.    SEE ALSO
  1514.        UMSSearch(), <usm.h>, </demo/SelectMail.c>
  1515.  
  1516.  
  1517. ums.library/UMSServerControl                     ums.library/UMSServerControl
  1518.  
  1519. ums.library/UMSWriteConfig                         ums.library/UMSWriteConfig
  1520.  
  1521.    NAME
  1522.  
  1523.        UMSWriteConfig -- Write an element to the UMS' configuration.
  1524.  
  1525.    SYNOPSIS
  1526.  
  1527.        success = UMSWriteConfig( login, tags )
  1528.          D0                       D2     D3
  1529.  
  1530.        BOOL UMSWriteConfig( LONG, struct TagIten * );
  1531.  
  1532.        success = UMSWriteConfigTags( login, tag1, ... )
  1533.  
  1534.        BOOL UMSWriteConfigTags( LONG, ULONG, ... );
  1535.  
  1536.  
  1537.    FUNCTION
  1538.  
  1539.        Create or modify elements of UMS' configuration.
  1540.  
  1541.    INPUTS
  1542.  
  1543.        The following tags are allowed:
  1544.  
  1545.        (Note: talking about a 'user' exporters and sysops are meant as well.)
  1546.  
  1547.        UMSTAG_CfgData (STRPTR)
  1548.  
  1549.          this tag's data holds the contents of the variable to be written.
  1550.          Use this tag in conjunction with UMSTAG_CfgName (see below).
  1551.  
  1552.        UMSTAG_CfgUser (STRPTR)
  1553.  
  1554.          name of the user whose local configuration should be changed. E.g.
  1555.          create a new alias or variable belonging to the specified user etc.
  1556.  
  1557.        UMSTAG_CfgGlobalOnly (none)
  1558.  
  1559.          change an element of the global configuration area being readable by
  1560.          all users.
  1561.  
  1562.        UMSTAG_CfgQuoted (LONG, V11)
  1563.  
  1564.          to store the variable's data in quoted format, allowing to mix the
  1565.          data and macro definitions, set the tag's data to 1 otherwise set it
  1566.          to 0 (or do not use this tag).
  1567.  
  1568.        UMSTAG_CfgLocal (none, V11)
  1569.  
  1570.          use this tag to create or delete variables that are only valid with
  1571.          the current login, disappearing after UMSLogout(). This way you can
  1572.          easily use UMSMatchConfig() without actually modifying the
  1573.          "ums.config".
  1574.  
  1575.        UMSTAG_CfgUnlockVar (STRPTR, V11)
  1576.  
  1577.          use this tag to unlock a variable locked by calling UMSReadConfig()
  1578.          with the UMSTAG_CfgLockVar tag allowing "public" access again. Set
  1579.          the tag's data to 1 to unlock and store the variable and its data,
  1580.          set it to 2 to just unlock the variable without actually saving it
  1581.          and set it to 0 (or don't use this tag) to not care about the
  1582.          current locking state of the variable.
  1583.  
  1584.  
  1585.        The following tags are mutually exclusive. Use exactly one of them.
  1586.  
  1587.        UMSTAG_CfgName (STRPTR)
  1588.  
  1589.          Name of the config variable to be changed. If a variable of the
  1590.          given name does not exist it will be created. To remove a variable
  1591.          from the configuration do not specify a tag UMSTAG_CfgData (see
  1592.          above).
  1593.  
  1594.        UMSTAG_CfgDump (STRPTR)
  1595.  
  1596.          write the current settings to a file with given name.
  1597.  
  1598.  
  1599.        UMSTAG_CfgCreateAlias (STRPTR, V11)
  1600.  
  1601.          create a new alias of the given name for the user specified by the
  1602.          UMSTAG_CfgUser tag (see above).
  1603.  
  1604.        UMSTAG_CfgDeleteAlias (STRPTR, V11)
  1605.  
  1606.          remove the alias of the given name from the user specified by the
  1607.          UMSTAG_CfgUser tag (see above).
  1608.  
  1609.        UMSTAG_CfgCreateExporter (STRPTR, V11)
  1610.  
  1611.          create a new export user with the given name.
  1612.  
  1613.        UMSTAG_CfgCreateSysop (STRPTR, V11)
  1614.  
  1615.          create a new user with sysop-privilegs with the given name.
  1616.  
  1617.        UMSTAG_CfgCreateUser (STRPTR, V11)
  1618.  
  1619.          create a new user with the given name.
  1620.  
  1621.        UMSTAG_CfgDeleteUser (STRPTR, V11)
  1622.  
  1623.          remove the user with the given name from the configuration deleting
  1624.          her local variables as well.
  1625.  
  1626.        UMSTAG_CfgAddNetGroup (STRPTR, V11)
  1627.  
  1628.          ???
  1629.  
  1630.        UMSTAG_CfgNetGroup (STRPTR, V11)
  1631.  
  1632.          ???
  1633.  
  1634.        UMSTAG_CfgDeleteNetGroup (STRPTR, V11)
  1635.  
  1636.          ???
  1637.  
  1638.    RESULT
  1639.  
  1640.        success - whether it was possible and allowed to make the desired
  1641.                    write or change.
  1642.  
  1643.    SEE ALSO
  1644.  
  1645.        UMSReadConfig()
  1646.  
  1647. ums.library/UMSWriteMsg                               ums.library/UMSWriteMsg
  1648.  
  1649.    NAME
  1650.        UMSWriteMsg -- Write a universal message to the UMS-MB.
  1651.  
  1652.    SYNOPSIS
  1653.        msgNum = UMSWriteMsg( login, tags )
  1654.          D0                   D3     D3
  1655.  
  1656.        LONG UMSWriteMsg( LONG, struct TagItem * );
  1657.  
  1658.        msgNum = UMSWriteMsgTags( login, tag1, ... )
  1659.  
  1660.        LONG UMSWriteMsgTags( LONG, ULONG, ... );
  1661.  
  1662.    FUNCTION
  1663.          Writes  a message to the UMS message-base.  This may be either a
  1664.        new  message  to  create  or  an  already  existing  message to be
  1665.        changed.
  1666.  
  1667.          The  MBP  checks  correctness  of  the  message  and  the  users
  1668.        write-access  concerning  this message before writing it.  It also
  1669.        performs  dupe-checking,  tries to link to a tree of reply-chains,
  1670.        creates   all  desired  indices  and  computes  the  other  users'
  1671.        read-access to this message.
  1672.          All  the components of the message as well as information on how
  1673.        to do it are supplied as AmigaDOS compatible TagItems.
  1674.  
  1675.    INPUTS
  1676.          The following tags are allowed:
  1677.  
  1678.          WMsgText, ..
  1679.          WMsgText + 127        : STRPTR
  1680.                specify a certain text-field.
  1681.                A  text fields is always one null-terminated string.  Read
  1682.        the  separate documantation to see what fields and what formats of
  1683.        these fields are allowed.
  1684.                A  certain  text-field  (identified  by  its tag) may only
  1685.        appear  once in a message.  If a field is specified more than once
  1686.        in the tag list, only the latest will be used.
  1687.  
  1688.          WTextFields           : UMSMsgTextFields
  1689.                specify more than one text-field.  This points to an array
  1690.        of 128 string-pointers.  All fields you don't want to specify must
  1691.        be NULL in this array.
  1692.  
  1693.  
  1694.          WMsgNum               : LONG
  1695.                when  you want to change an old message, you must use this
  1696.        tag  to  specify  the  number of the message to change.  Don't use
  1697.        this tag when you just want to create a new message.
  1698.  
  1699.          WMsgDate              : LONG
  1700.                this  has  a very special meaning.  Specifying an AmigaDOS
  1701.        compatible  date  (seconds since 1.1.1978) with this tag indicates
  1702.        that you  want to restore an old message from a backup rather than
  1703.        writing a new one.  All users will have the 'old' flag set and not
  1704.        get this message as a new one when this tag is used.
  1705.  
  1706.        WChainUp                : LONG
  1707.                in some cases it might be unsure or impossible for the MBP
  1708.        to  build  the correct reply-chain for a message.  Use this tag to
  1709.        specify  the  number of the old message that is referred to by the
  1710.        new one.
  1711.  
  1712.        WHardLink,
  1713.        WSoftLink               : LONG
  1714.                Writing a message with a Message-ID that already exists in
  1715.        the  MB  usually  will  lead to the detection of a 'dupe'.  Yet in
  1716.        some cases it is necessary for UMS to allow multiple messages with
  1717.        the  same  Message-ID.
  1718.                This  is  made possible by the concept of message-'links'.
  1719.        With  this  concept, multiple messages sharing the same Message-ID
  1720.        (and  perhaps some more fields) are organized in a circular linked
  1721.        list.   To  create  such  a  linked list, you just write its first
  1722.        message  as  usual  and  remember  its number.  Then you write the
  1723.        other  messages  using one of the above tags to specify the number
  1724.        of the original message (or any of the already linked messages).
  1725.                The  MBP  may  optimize storage space for message links by
  1726.        only  storing  the  fields  that differ between the fields and the
  1727.        original  message.   Nevertheless  you  always have to specify the
  1728.        whole message to write a link and you will always get the complete
  1729.        message when reading a link.
  1730.                All  links to a message must consist of the same fields as
  1731.        the original message, but the contents of the fields may differ.
  1732.  
  1733.                There  are  two  sorts  of  message-links,  hardlinks  and
  1734.        softlinks.   Softlinks  describe messages that have some fields in
  1735.        common  (at  least  the  Message-ID),  but  are  really treated as
  1736.        individual  messages.   E.g.   different parts of a splitted large
  1737.        message.  Hardlinks, on the other hand, are treated as one message
  1738.        wherever  possible.  I.e.  if you read one hardlinked message, all
  1739.        the  other  links  will be marked as old, too.  RFC crosspostings,
  1740.        for instance, should be made hardlinks.
  1741.  
  1742.        WAutoBounce             : LONG
  1743.                If the msg to be written is addressed to a local user that
  1744.        doesn't  exist or to an address that no exporter can export, there
  1745.        are two possible behaviours possible for the MBP:
  1746.                a) reject the message using error-no "NoReader", expecting
  1747.        the client to care about the undeliverable message
  1748.                b)  keep  the message, forwarding it to the local sysop or
  1749.        some kind of 'bounce-daemon', so that the writing client needs not
  1750.        to care about the message any more.
  1751.                This  tag allowes to specify the desired behaviour, data=0
  1752.        forces  a),  data=1  forces b).  If this tag is not specified, the
  1753.        MBP  will  choose  the  behaviour as it wishes, maybe depending on
  1754.        whether the writing user is an exporter or not.
  1755.  
  1756.        WHide                   : LONG
  1757.                In  some  cases  it  might be desirable to write a message
  1758.        that can only by read by exporters and not by simple users, or the
  1759.        other way round.
  1760.                For  instance  control-messages that are of no interest to
  1761.        users by must be distributed over the net.
  1762.                Setting data to 0 is the same as the default. data=1 means
  1763.        that  only  exporters  may view and read the message, data=2 makes
  1764.        the  message  invisible to exporters and only accessible to simple
  1765.        users.
  1766.  
  1767.        WHdrFill,
  1768.        WTxtFill                : LONG
  1769.                specify how many bytes to reserve for later changes in the
  1770.        header/text of the message.
  1771.                The  MBP  may not be able to change an existing message if
  1772.        the   change   would   increase  the  overall  size  (maybe  after
  1773.        compression) of the message.  Since such changes are neccessary in
  1774.        some special cases, the MBP can be told to reserve some space when
  1775.        writing a message the first time.
  1776.  
  1777.                Reserving  more  than  actually needed is not a good idea,
  1778.        since  it decreases performance and wastes space.  The writer of a
  1779.        message  usually  should  know  whether  or not he will change the
  1780.        message  later on  and to what extend he will increase the size of
  1781.        the message.
  1782.  
  1783.          WNoUpdate              : LONG
  1784.         when writing a message, the 'Old'-flag in your user-status
  1785.        for  the new message will usually be set.  If you don't want this,
  1786.        use this tag and set its data to 1.
  1787.  
  1788.    RESULT
  1789.        msgNum - Number of the written message or NULL on failure.
  1790.  
  1791.    NOTES
  1792.                Changing an old message:
  1793.  
  1794.                You   must   _always_   give   a   complete   message   to
  1795.        WriteUMSMsg(),  even when changing an old one!  The MBP needs this
  1796.        to  detect all changes made to the old message, including changed,
  1797.        added or deleted fields.  Thus you need to read a message prior to
  1798.        changing  it.  Use RTextFields and WTextField for ReadUMSMsg() and
  1799.        WriteUMSMsg()  when  changing  an old message!  Otherwise you will
  1800.        loose  fields  unknown  to  you  allication  that  might  be still
  1801.        important to other applications!
  1802.  
  1803.                You  may  not  be  allowed  to change certain fields of an
  1804.        existing  message.   Most likely those fields that are used by the
  1805.        MBP  to  compute all the users access-rights will be prohibited to
  1806.        change.
  1807.  
  1808.    SEE ALSO
  1809.        utility/tagitem.h
  1810.  
  1811.